LScript User Guide
Next Section Previous Section Table of Contents Index Errata

LScript Object Agents

The LScript environment contains built-in "objects" that can be used to interface with operating system-level functions and data types. These internal objects, known as Object Agents, are documented in the following sections.

File Object Agent

The LScript File Object Agent provides access to an operating system's disk file management functionality. The LScript built-in command File() returns an object of this type. Once assigned to a variable, the following File Object Agent methods can be accessed through the host variable:

isOpen

Returns a boolean value indicating that the file is indeed open and accessible.

     isOpen(void)

open

Opens a new file with a specified mode. The newly opened file is assigned to the existing File Object Agent.

     void open(name,               // string; disk file
                                        // to open
               mode)               // string; mode to use for
                                        // open

reopen

Closes the currently open file, and reopens it in the specified mode.

     void reopen(mode)             // string; mode to use for
                                        // file open

close

Closes the currently open file.

     void close(void)

eof

Returns a boolean value (true/false) indicating whether the file has reached the EOF marker.

     result                        // boolean; true or false
       eof(void)

rewind

Resets the file read/write point to the beginning of the file.

     void rewind(void)

name

Returns a string containing the name (and path, if it was originally specified) of the currently open file.

     result                        // string; file name
       name(void)

write, writeln

write() places a series of one or more arguments to the file. writeln() is identical to write() except that a newline character is appended to the line.

These commands are illegal when the file is opened in Binary mode.

     result                        // integer; number of bytes
                                        // written to file
       write(item1[,itemN])        // data type; one or more
                                        // variables or
                                        // constants

read

Reads a text line from the file, returning it as a character string. This function is illegal when the file is opened in Binary mode.

     result                        // string; text line from
                                        // file
       read(void)

readNumber

In ASCII mode, this function reads a sequence of characters from the file, converting them to a single numeric value. In Binary mode, a single integer value is read from the file.

     result                        // number; a floating-point
                                        // value
       readNumber(void)

readVector

In ASCII mode, this function will read a sequence of characters from the file, return them as a vector data type. The data in the file should appear as space-separated, floating-point numbers.

In Binary mode, three numeric values of size double will be read and returned as a vector.

     result                        // vector; the vector as it
                                        // appears in the file
       readVector(void)

parse

Read a line from the file, and returns a variable number of elements representing the tokens of the line. Tokens are separated by one of the characters provided in the character string argument.

This function is illegal in Binary mode.

     result                        // string[]; array of
                                        // character strings
                                        // representing
                                        // tokens
       parse(token)                // string; a character
                                        // string of tokens
                                        // separators

nl

Writes a newline character to the file. This command is illegal in Binary mode.

     void nl(void)

linecount

When the file is opened in ASCII mode, this function returns the number of text lines in the currently-open file. However, in Binary mode, it returns the size, in bytes, of the file.

     result                        // integer; line or byte
                                        // count of file
       linecount(void)

line

In ASCII mode, this function returns the current line number in the file when no argument is provided. When a integer value is provided that falls within the range of text lines in the file, it will move the file pointer to the line number indicated.

This command is illegal in Binary mode.

     result                        // integer; current line
                                        // number when
                                        // optional parameter
                                        // is omitted
       line([linenumber])          // integer; the line number
                                        // to which the file
                                        // should be
                                        // positioned

readInt

In ASCII mode, this function will read a sequence of characters from the text file and return an integer data type. In Binary mode, a single binary value of size integer will be read from the file.

     result                        // integer; an integer
                                        // value from the file
       readInt(void)

readByte

In ASCII mode, this function will return a single character from the text file as a integer value. In Binary mode, a single binary value of size unsigned char is read from the file and returned as an integer value.

     result                        // integer; single byte
                                        // from the file
       readByte(void)

writeNumber

In ASCII mode, the value provided is written into the text file as a floating-point number in character format. In Binary mode, a single binary value of size double is written to the file.

     result                        // integer; number of bytes
                                        // written to file
       writeNumber(value)          // number; floating-point
                                        // value

writeInt

In ASCII mode, the value provided is written into the text file as an integer numeric value in character format. In Binary mode, a single binary value of size integer is written to the file

     result                        // integer; number of bytes
                                        // written to file
       writeInt(value)             // integer; the value to be
                                        // written

writeByte

In ASCII mode, the integer value proved is written into the text file as a character. In Binary mode, the provided value is stored in the file as a single binary value of size unsigned character.

     result                        // integer; number of bytes
                                        // written to file
       writeByte(value)            // integer; the value to be
                                        // written

offset

Called without parameters, this method will return the current byte offset of the file. Providing an integer value will cause the file pointer to be placed at the specified offset in the file, relative to an offset method. This optional offset method can be one of: FROMSTART, which will position the file from the beginning (and is the default when no method is specified); FROMEND, which will position from the end of the file; and FROMHERE, which assumes that the provided offset value is relative to the current location of the pointer.

     result                        // integer; current offset
                                        // in file
       offset([value               // integer; offset to be
                                        // used
              [,method]])          // constant; FROMSTART,
                                        // FROMEND or FROMHERE
Please refer to the numerous example LScripts supplied with LightWave 3D for further examples of using the LScript File Object Agent.

User-created Object Agents

LScript provides an extension mechanism that allows software prorammers to create new Object Agents. This support, and the steps required to take advantage of it, are documented in APPENDIX B: Extending LScript Shared Libraries: User-Defined Object Agents.


Next Section Previous Section Table of Contents Index Errata
© 1996 Virtual Visions, Inc.
© 1997 NewTek, Inc.